<html>
<!-- $LastChangedDate: 2009-12-16 19:28:57 -0500 (Wed, 16 Dec 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Sound Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Sound Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Class Design'>Class Design</a></li>
  <li><a href='#SoundBase'>SoundBase</a></li>
  <li><a href='#Sample'>Sample</a></li>
  <li><a href='#SDL Implementation'>SDL Implementation</a></li>
  <li><strike><a href='#PLIB Implementation'>PLIB Implementation</a></strike></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2007/12..2009/12]</p>
<p>
Sound class plays sound files, can loop the same sound, and can adjust volume.
Program will initiate asynchronous playing of a sound file (sample) by calling Sound::Play().
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Class Design'></a>
<h2>Class Design</h2>
<p><!--date-->[2009/12]</p>
<p>
A derivative of <a href='#SoundBase'>SoundBase</a> initializes the sound system and controls the master volume.
<br>A derivative of <a href='#Sample'>Sample</a> plays sound files.
<br>SoundBase provides caching of Samples.
<br>SoundBase is able to define the Sample-related methods,
but defers other functionality to a SoundBase derivative.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='SoundBase'></a>
<h2>SoundBase</h2>
<p><!--date-->[2009/12]</p>
<p>
SoundBase provides generic functionality.
SoundBase controls sound samples in terms of the base <a href='#Sample'>Sample class</a>.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Sample'></a>
<h2>Sample</h2>
<p><!--date-->[2009/12]</p>
<p>
<i>Sample</i> means a waveform which is typically loaded from a sound file.
The base Sample class defines a generic interface used by the <a href='#SoundBase'>SoundBase</a> class.
The derivatives of the Sample class are specific to a sound system
and do the actual playing of a sound.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='SDL Implementation'></a>
<h2>SDL Implementation</h2>
<p><!--date-->[2009/12]</p>
<p>
SDL_mixer is used.
The SDL_RWop mechanism is used to read gzip-compressed sound files.
SoundSDL creates either a SampleSDLWave or SampleSDLMusic object
according to the kind of sound file.
Difference between WAV/MUS is how many and which channels are used.
</p>

<h3>SDL wave vs. music, SDL misnomers</h3>
<p><!--date-->[2009/12]</p>
<!-- from sound_sdl.hh -->
<p>
Wave means a sample/chunk.
A SDL wave object is bound to a channel.
A SDL music object isn't.
Whether a sound file is a wave or music is determined
when trying to use a SDL WAV() or MUS() function.
SDL sound functions are misnomers, for example,
SDL_*WAV() can load OGG etc music files too.
</p>

<h3>SDL's underlying sound libraries</h3>
<p><!--date-->[2009/12]</p>
<!-- from sound_sdl.hh -->
<p>
<ul>
  <li>What works well:</li>
      <p>
      Playing WAV and OGG.
      </p>
  <li>What doesn't:</li>
      <p>
      Note that SDL_mixer is linked with various OPTIONAL LIBRARIES.
      The underlying SMPEG library is flakey and won't play all kinds of MPEGs.
      Playing MIDI does work well but requires timidity.
      On Debian 5 Linux, timidity has to run as a daemon.
      </p>
  <li>Summary:</li>
      <p>
      Prefer .wav since SDL_mixer contains WAV code.
      Per the code of Mix_LoadWAV_RW(), no other kinds of sound is intrinsic.
      </p>
</ul>

<!-- ----------------------------------------------------------------------- -->
<strike>
<hr>
<a name='PLIB Implementation'></a>
<h2>PLIB Implementation</h2>
<p><!--date-->[2007/12]</p>
<p>
The developers of PLIB decided to require the application
to perodically pulse PLIB to play sounds,
deferring the choice of the frequency of the tick to the app developer.
PLIB will play a segment of a sample once every tick.
Therefore, the Sound class has a timer-tick functor.
</p>
<p>
PLIB alters a sample's volume by modifying its waveform (slow operation).
The Sound class avoids PLIB distorting the waveform by restoring
the original waveform (so changing volume becomes even slower).
</p>
<p>
PLIB will cause program exit if a sample is deleted while still playing.
stopSample() and update() don't quite work according to the PLIB docs.
The reliable way is to enqueue zombie samples then deleted them
when their "play count" reaches zero.
</p>
</strike>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Wed Dec 16 16:53:16 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
